home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 April: Mac OS SDK / Dev.CD Apr 98 SDK2.toast / Development Kits (Disc 2) / QuickTime / Programming Stuff / Documentation / develop articles / develop Issue 23 / Internet Config / IC 1.1 / ICProgKit1.1 / APIs / ICAPI.p < prev    next >
Encoding:
Text File  |  1997-02-26  |  10.8 KB  |  218 lines  |  [TEXT/PJMM]
  1. unit ICAPI;
  2.  
  3. interface
  4.  
  5.     uses
  6. {$ifc undefined THINK_Pascal}
  7.         Types, Files, QuickDraw, AppleTalk, Aliases, 
  8. {$endc}
  9.         ICTypes, ICKeys;
  10.  
  11.     function ICStart (var inst: ICInstance; creator: OSType): ICError;
  12.     (* call at application initialisation *)
  13.  
  14.     function ICStop (inst: ICInstance): ICError;
  15.     (* call at application termination *)
  16.  
  17.     function ICFindConfigFile (inst: ICInstance; count: integer; folders: ICDirSpecArrayPtr): ICError;
  18.     (* count is the number of ICDirSpecs that are valid in folders *)
  19.     (* searches the specified folders first, then backs out to preferences folder *)
  20.     (* don't you worry about how it finds the file (; *)
  21.     (* you can pass nil to folders if count is 0 *)
  22.  
  23.     function ICFindUserConfigFile (inst: ICInstance; where: ICDirSpec): ICError;
  24.     (* requires IC 1.1 *)
  25.     (* similar to ICFindConfigFile except *)
  26.     (* For use with double clickable preference files, this searches only the where directory *)
  27.  
  28.     function ICSpecifyConfigFile (inst: ICInstance; config: FSSpec): ICError;
  29.     (* for use *only* by Internet Configuration application *)
  30.  
  31.     function ICGetSeed (inst: ICInstance; var seed: longint): ICError;
  32.     (* returns current seed for prefs file *)
  33.     (* this seed changes every time a preference is modified *)
  34.     (* poll this to detect preference changes by other applications *)
  35.  
  36.     function ICGetPerm (inst: ICInstance; var perm: ICPerm): ICError;
  37.     (* returns the permissions currently associated with this file *)
  38.     (* mainly used by overriding components, applications normally *)
  39.     (* know what permissions they have *)
  40.  
  41.     function ICBegin (inst: ICInstance; perm: ICPerm): ICError;
  42.     (* start reading/writing the preferences *)
  43.     (* must be balanaced by a ICEnd *)
  44.     (* do not call WaitNextEvent between this pair *)
  45.     (* specify either icReadOnlyPerm or icReadWritePerm *)
  46.     (* note that this may open resource files and leave them open until ICEnd *)
  47.  
  48.     function ICGetPref (inst: ICInstance; key: Str255; var attr: ICAttr; buf: Ptr; var size: longint): ICError;
  49.     (* this routine may be called without a ICBegin/ICEnd pair, in which case *)
  50.     (* it implicitly calls ICBegin(inst, icReadOnlyPerm *)
  51.     (* given a key string, returns the attributes and the (optionally) the data for a preference *)
  52.     (* key must not be the empty string *)
  53.     (* if buf is nil then no data fetched and incoming size is ignored*)
  54.     (* size must be non-negative, is size of allocated space for data at buf *)
  55.     (* attr and size and always set on return *)
  56.     (* size is actual size of data (if key present) *)
  57.     (* attr is pref attributes *)
  58.      (* if icTruncatedErr then everything is valid, except you lost some data, size is size of real data*)
  59.     (* on other errors, attr is ICattr_no_change and size is 0 *)
  60.  
  61.     function ICSetPref (inst: ICInstance; key: Str255; attr: ICAttr; buf: Ptr; size: longint): ICError;
  62.     (* this routine may be called without a ICBegin/ICEnd pair, in which case *)
  63.     (* it implicitly calls ICBegin(inst, icReadWritePerm *)
  64.     (* given a key string, sets the attributes and the data for a preference (either is optional) *)
  65.     (* key must not be the empty string *)
  66.     (* if buf is nil then no data stored and size is ignored, used for setting attr *)
  67.     (* size must be non-negative, is size of the data at buf to store *)
  68.     (* icPermErr if ICBegin was given icReadOnlyPerm *)
  69.     (* icPermErr if current attr is locked, new attr is locked and buf <> nil *)
  70.  
  71.     function ICGetPrefHandle (inst: ICInstance; key: Str255; var attr: ICAttr; var prefh: Handle): ICError;
  72.     (* same as ICGetPref except that it returns the result in a newly created handle *)
  73.     (* prefh is set to a newly created handle *)
  74.  
  75.     function ICSetPrefHandle (inst: ICInstance; key: Str255; attr: ICAttr; prefh: Handle): ICError;
  76.     (* same as ICSetPref except that it sets the preference based on a handle *)
  77.     (* prefh must not be nil *)
  78.  
  79.     function ICCountPref (inst: ICInstance; var count: longint): ICError;
  80.     (* count total number of preferences *)
  81.     (* if error then count is 0 *)
  82.  
  83.     function ICGetIndPref (inst: ICInstance; n: longint; var key: Str255): ICError;
  84.     (* return the key of the Nth preference *)
  85.     (* n must be positive *)
  86.     (* icPrefNotFoundErr if n is beyond the last preference *)
  87.  
  88.     function ICDeletePref (inst: ICInstance; key: Str255): ICError;
  89.     (* delete the preference specified by key *)
  90.     (* key must not be the empty string *)
  91.     (* preference specified by key must be present *)
  92.     (* icPrefNotFoundErr if it isn't *)
  93.  
  94.     function ICEnd (inst: ICInstance): ICError;
  95.     (* stop reading/writing the preferences *)
  96.  
  97.     function ICDefaultFileName (inst: ICInstance; var name: Str63): ICError;
  98.     (* return the default file name *)
  99.     (* the component calls this routine to set up the default internet configuration file name*)
  100.     (* this allows this operation to be intercepted by a component that has captured us *)
  101.     (* it currently gets it from the component resource file *)
  102.     (* the glue version is hardwired *)
  103.  
  104.     function ICGetComponentInstance (inst: ICInstance; var component_inst: univ Ptr): ICError;
  105.     (* returns noErr and the component instance that we're talking to, if we're using the component *)
  106.     (* returns an error and nil if we're doing it with glue *)
  107.     (* univ Ptr rather than ComponentInstance so that you don't need Components.p *)
  108.     (* in order to use this file *)
  109.  
  110.     function ICEditPreferences (inst: ICInstance; key: Str255): ICError;
  111.     (* requires IC 1.1 *)
  112.     (* this routine may be called without a ICBegin/ICEnd pair *)
  113.     (* open the IC application and edits the preference *)
  114.     (* you must have found a config file before calling this *)
  115.     (* if key is empty then it just opens the application with the found config file *)
  116.     (* otherwise it displays the preference with the specified key *)
  117.     (* may have an implementation that is radically different in the future *)
  118.  
  119.     function ICParseURL (inst: ICInstance; hint: Str255; data: Ptr; len: longint; var selStart, selEnd: longint; url: Handle): ICError;
  120.     (* requires IC 1.1 *)
  121.     (* this routine may be called without a ICBegin/ICEnd pair *)
  122.     (* parses a URL out of a chunk of text and returns it in a canonical form *)
  123.     (* hint is an indication of how you want slack URLs to be parsed *)
  124.     (* data points to the beginning of the text *)
  125.     (* len is the length of the text *)
  126.     (* selStart is the start of the current selection *)
  127.     (* selEnd is the end of the current selection *)
  128.     (* both of these are interpreted as per TextEdit *)
  129.     (* both of these are adjusted to indicate the bounds of the text that was interpreted as a URL *)
  130.     (* the URL is copied into the url handle, which is resized to accomodate the URL *)
  131.  
  132.     function ICLaunchURL (inst: ICInstance; hint: Str255; data: Ptr; len: longint; var selStart, selEnd: longint): ICError;
  133.     (* requires IC 1.1 *)
  134.     (* this routine may be called without a ICBegin/ICEnd pair *)
  135.     (* identical to ParseURL but it launches the appropriate application (as specified in the 'Helper•' preference *)
  136.     (* and sends it a GURL AppleEvent *)
  137.     (* your code must be running in the context of a high level event aware application for this to work *)
  138.  
  139.     (* ----- Mappings Routines ----- *)
  140.  
  141.     (* Routines for interrogating mappings database *)
  142.     (* All of these routines require IC 1.1 *)
  143.  
  144.     (* High Level Routines *)
  145.  
  146.     (* you do not need to call begin/end around any of these high level routines *)
  147.     (* but if you're going to call them repeatedly, it will help *)
  148.  
  149.     function ICMapFilename (inst: ICInstance; filename: Str255; var entry: ICMapEntry): ICError;
  150.     (* high level interface to the mappings database *)
  151.     (* takes a filename and returns the incoming entry associated with that file's extension *)
  152.     (* or errors with icPrefNotFoundErr *)
  153.  
  154.     function ICMapTypeCreator (inst: ICInstance; fType, fCreator: OSType; filename: Str255; var entry: ICMapEntry): ICError;
  155.     (* high level interface to the mappings database *)
  156.     (* takes a filename and returns the outgoing entry associated with that type, creator and filename *)
  157.     (* or errors with icPrefNotFoundErr *)
  158.  
  159.     (* Mid Level Routines *)
  160.  
  161.     (* you do not need to call begin/end around any of these mid level routines *)
  162.  
  163.     function ICMapEntriesFilename (inst: ICInstance; entries: Handle; filename: Str255; var entry: ICMapEntry): ICError;
  164.     (* mid level interface to the mappings database *)
  165.     (* entries must be a valid IC mappings database handle *)
  166.     (* takes a filename and returns the incoming entry associated with that file's extension *)
  167.     (* or errors with icPrefNotFoundErr *)
  168.  
  169.     function ICMapEntriesTypeCreator (inst: ICInstance; entries: Handle; fType, fCreator: OSType; filename: Str255; var entry: ICMapEntry): ICError;
  170.     (* mid level interface to the mappings database *)
  171.     (* entries must be a valid IC mappings database handle *)
  172.     (* takes a filename and returns the outgoing entry associated with that type, creator and filename *)
  173.     (* or errors with icPrefNotFoundErr *)
  174.  
  175.     (* Low Level Routines *)
  176.  
  177.     (* you do not need to call begin/end around any of these low level routines *)
  178.  
  179.     function ICCountMapEntries (inst: ICInstance; entries: Handle; var count: longint): ICError;
  180.     (* entries must be a valid IC mappings database handle *)
  181.     (* count the number of entries in the Mappings database *)
  182.  
  183.     function ICGetIndMapEntry (inst: ICInstance; entries: Handle; ndx: longint; var pos: longint; var entry: ICMapEntry): ICError;
  184.     (* entries must be a valid IC mappings database handle *)
  185.     (* return the ndx'th entry in the mappings database *)
  186.     (* ndx must be from 1 to CountMapEntries *)
  187.     (* pos is ignored on input and comes back as the position of the entry in the database *)
  188.     (* entry is ignored on input and comes back as the database entry at the ndx position *)
  189.  
  190.     function ICGetMapEntry (inst: ICInstance; entries: Handle; pos: longInt; var entry: ICMapEntry): ICError;
  191.     (* entries must be a valid IC mappings database handle *)
  192.     (* return the entry at position pos *)
  193.     (* pos should be a valid entry start position *)
  194.     (* set pos to 0 for the first entry *)
  195.     (* set pos to pos + entry.total_size for subsequent entries *)
  196.     (* entry is ignored on input and comes back as the database entry at position pos *)
  197.  
  198.     function ICSetMapEntry (inst: ICInstance; entries: Handle; pos: longInt; var entry: ICMapEntry): ICError;
  199.     (* entries must be a valid IC mappings database handle *)
  200.     (* set the entry at position pos *)
  201.     (* pos should be a valid entry start position *)
  202.     (* any user data at the end of the entry is preserved *)
  203.     (* entry is not modified, it's a var parameter simply to preserve stack space *)
  204.  
  205.     function ICDeleteMapEntry (inst: ICInstance; entries: Handle; pos: longint): ICError;
  206.     (* entries must be a valid IC mappings database handle *)
  207.     (* delete the entry at position pos *)
  208.     (* pos should be a valid entry start position *)
  209.     (* also deletes the user data associated with the entry *)
  210.  
  211.     function ICAddMapEntry (inst: ICInstance; entries: Handle; var entry: ICMapEntry): ICError;
  212.     (* entries must be a valid IC mappings database handle *)
  213.     (* add entry to the mappings database *)
  214.     (* entry is not modified, it's a var parameter simply to preserve stack space *)
  215.  
  216. implementation
  217. end. (* ICAPI *)
  218.